昨天，我們把網站從 Wireframe、Mockup 一路看到 Prototype，總算把「這個產品應該長什麼樣子」慢慢對齊了。
但真的要開始寫 Code 以前，還有另一個角色也需要先對齊：
AI。
以前我用 AI 輔助開發功能時，會把那些專案規則一直塞進當下 Prompt：
「改了資料模型記得一起做 migration。」
「這類修改完成後要跑對應測試。」
「做 UI 前先看我們的視覺規格文件。」
一次兩次還好。
但只要開一個新的 Session，又得重新講一遍。
而且 Claude Code 官方文件一開始就直接提醒了一件很重要的事：
每一次新的工作階段（Session），都是一個全新的脈絡視窗（Context Window）。
翻成白話就是：
你昨天跟它講過的所有事情，今天全部歸零。
所以 Claude Code 和 Codex 都提供了一種很重要的機制：
把長期需要 AI 知道的專案規則，直接寫進專案裡。
這就是 CLAUDE.md、AGENTS.md 這類文件在做的事。
可以先把它們理解成：
專門寫給 Coding Agent 看的工作規則。
其中，Claude Code 主要使用 CLAUDE.md。
而 AGENTS.md 不是 Codex 專屬的檔案，而是一種給 Coding Agent 使用的開放格式。Codex 支援它，另外也有其他 Coding Agent 和開發工具採用這個格式。
所以它們不是同一套系統，但背後要解決的問題很接近：
讓 Coding Agent 在開始工作以前，先知道這個專案有哪些長期需要遵守的規則。
例如：
# Development Rules
- 修改介面時遵守既有視覺規格
- 修改資料模型後建立對應 migration
- 修改認證邏輯時補上測試
這些不是「這一次任務」才臨時出現的要求。
而是：
只要在這個專案裡工作，就長期成立的規則。
所以它和一般 Prompt 扮演的角色不太一樣。
Prompt 比較像：
這一次，幫我修改登入頁。
CLAUDE.md / AGENTS.md 比較像：
不管你今天要改什麼，先知道這間廚房平常怎麼工作。
如果把 Coding Agent 想成剛進甜點工作室的新夥伴，我不需要每次請它做一顆蛋糕，都重新介紹一次烤箱放在哪裡、出餐標準是什麼、哪些材料不能亂換。
那些長期規則，本來就應該有一個固定的位置。
我第一次看到這類檔案時，其實也會想：
「這不就是 README 嗎？」
兩者的確可能會有一些內容重疊，但主要服務的讀者不同。
| 文件 | 主要讀者 | 比較適合放什麼 |
|---|---|---|
README.md |
人 | 專案用途、安裝方式、啟動方式、技術介紹 |
CLAUDE.md / AGENTS.md |
Coding Agent | 工作規則、慣例、限制、完成標準、重要文件位置 |
例如：
這個專案使用 Vue 3。
比較像專案背景。
但：
新增 UI 以前，先檢查現有共用元件，不要另外建立重複元件。
就是一條很明確的工作規則。
所以如果先用最白話的方式分：
README.md 主要是給人看的專案說明；CLAUDE.md / AGENTS.md 則是給 Coding Agent 看的工作說明。
這類文件另一個很重要的概念，就是 Scope（作用範圍）。
不是所有規則都一定要塞進專案根目錄。
有些是我自己跨所有專案都會用到的偏好。
有些是整個團隊共同遵守的專案規範。
還有一些，只跟某個專案、某個資料夾，甚至只跟我自己有關。
以 Claude Code 來說，可以先把 Scope 想成幾個不同層級：
| Scope | 檔案 | 適用範圍 |
|---|---|---|
| 使用者層 | ~/.claude/CLAUDE.md |
只有自己，但跨所有專案 |
| 專案層／團隊 | ./CLAUDE.md 或 ./.claude/CLAUDE.md |
目前專案，團隊共用 |
| 專案層／個人 | ./CLAUDE.local.md |
只有自己＋目前這個專案，通常不進版控 |
| 子資料夾層 | 子資料夾裡的 CLAUDE.md / CLAUDE.local.md |
只在處理該區域相關工作時使用 |
例如：
~/.claude/CLAUDE.md 可以放我自己跨所有專案都習慣的工作方式。
專案根目錄的 CLAUDE.md，則適合放整個團隊在這個專案裡共同遵守的規則。
如果有一些規則只有我自己在這個專案裡需要，例如個人的 sandbox URL、測試資料偏好，或不需要分享給團隊的開發習慣，就可以放在 CLAUDE.local.md。
因為它只屬於自己，所以通常會加進 .gitignore，不提交進版本控制。
而如果某些規則只跟特定資料夾有關，也可以再往更深的目錄放。
例如：
project/
├── CLAUDE.md
├── CLAUDE.local.md
├── frontend/
│ └── CLAUDE.md
└── backend/
└── CLAUDE.md
根目錄的 CLAUDE.md 可以放整個專案都要遵守的共同規則：
- 修改完成後執行測試
- 不提交敏感資訊
而 frontend/CLAUDE.md 再補上更貼近前端工作的規則：
- UI 遵守 Design System
- 修改畫面時確認 Desktop / Mobile
這些規則不是彼此完全獨立，而是會依照工具自己的載入機制一起作用。
外層負責比較廣泛的共同規則。
越往專案內部、越靠近實際工作的資料夾，就可以補上越貼近那個情境的規則。
所以分層真正重要的不是：
「我要多寫幾份文件。」
而是：
「這條規則到底應該管多大的範圍？」
跨所有專案都適用的，放使用者層。
整個專案都需要的，放專案層。
只有自己在這個專案需要的，放 CLAUDE.local.md。
只有某個區域需要的，就往更靠近那個資料夾的位置放。
規則會疊加，而越靠近實際工作的地方，就越能補上更精準的情境資訊。
不過這裡也要注意：至少在 Claude Code 裡，不能簡化成「越內層就一定硬性覆蓋外層」。
這些內容會一起進入 Context；如果規則彼此衝突，最好不要依賴固定的覆蓋順序，而是直接把規則寫得一致，或在更具體的文件裡明確說清楚哪一條應該優先。
所以 Scope 的目的不是製造互相打架的規則，而是：
讓共同規則留在外層，情境越特殊，規則就放得越靠近真正需要它的地方。
/init知道它是什麼之後，下一個問題就是：
「好，那第一份我要自己從零開始寫嗎？」
不用。
Claude Code 和 Codex 都有一個很方便的起點：
/init
Claude Code 可以用 /init 幫目前的 Codebase 建立一份起始版 CLAUDE.md。
Codex 也可以用 /init，替目前專案產生 AGENTS.md 的基本架構。
AI 會先掃過目前的專案，再整理出一份初始文件。
通常會包含像：
超級方便。
第一次看到真的很容易有一種：
「欸？那我是不是打一行就結束了（笑）」
的感覺。
但問題也剛好出在這裡：
它很容易太完整。
/init 是起點，不是完成版AI 掃完整個專案之後，很自然會把它看到的東西整理進去。
例如：
這個專案使用 Vue
這個專案使用 Express
有 components 資料夾
有 controllers 資料夾
package.json 裡有哪些 scripts
問題是：
其中很多東西，下一次 AI 自己再掃一次專案還是找得到。
如果本來幾秒就能從 package.json、目錄結構或 Code 看出來，我們就要開始問：
真的值得讓 AI 每一次開工以前，都重新讀一次嗎？
這也是 Claude Code 官方在談這類文件修剪時很強調的方向。
Claude Code 有一個健檢指令 /doctor，官方給出的修剪思路其實很直接：
把 AI 自己能從 Code 推導出來的內容砍掉。
像：
反而留下：
所以我會把 /init 想成：
先幫我把材料全部倒到料理台上。
接下來不是繼續加東西。
是先挑掉那些根本不用一直放在桌上的材料。
面對 /init 產生的內容，我覺得可以先問三個問題。
| 問題 | 判斷方式 |
|---|---|
| AI 自己找得到嗎？ | 翻一下 Code、README、package.json 就知道的資訊，需要每次重複讀嗎？ |
| 大部分工作真的都會用到嗎？ | 如果只跟前端或某個資料夾有關，是否應該移到更精準的 Scope？ |
| 過一陣子還會成立嗎？ | 很快可能過期的暫時性規則，適合一直留在長期指令裡嗎？ |
這三題其實都在做同一件事：
判斷這條資訊到底值不值得每次跟著 Coding Agent 一起進入工作脈絡。
AI 自己找得到。
不是大部分任務都需要。
又很容易過期。
這類資訊就不用急著一直留著。
減完之後，才進到真正重要的第二步：
把 AI 自己不一定知道，但我們真的很希望它知道的事情加回來。
這裡我會用五種類型來判斷。
| 類型 | 要留下什麼 |
|---|---|
| 不能搞錯的規則 | 光看 Code 不一定知道，但做錯會出問題的業務或安全決策 |
| 固定的處理方式 | 團隊做某件事時固定遵守的順序或流程 |
| 容易漏掉的連動關係 | 改 A 時，還有哪些地方必須一起確認 |
| 完成定義（Definition of Done） | 做到什麼程度才叫真的完成 |
| 重要資料的位置 | 不把整份規範塞進來，而是告訴 AI 真正答案去哪裡找 |
這五種類型有一個共同點：
它們通常不是 Coding Agent 單純掃 Code 就一定能理解的東西。
Code 可以讓 AI 看見：
這裡有 Rate Limiter。
但不一定能告訴它：
這是團隊刻意留下的安全設計，不應該為了方便就直接拿掉。
Code 也可以讓 AI 看見很多測試。
但不一定能告訴它：
團隊把「補完對應測試」當成某一類修改的完成條件。
這些「團隊自己知道、但 Code 不一定說得完整」的資訊，才是這類文件很有價值的地方。
第五種「重要資料的位置」，我覺得特別值得拆出來講。
因為很容易發生另一個極端：
既然 AI 要知道設計規範，那就把整份設計規範全部貼進 AGENTS.md。
既然 AI 要知道部署流程，那整份 Deployment Guide 也一起搬進來。
久了以後，一份文件就變成大型百科全書。
其實完全不用。
例如：
介面實作請遵守：
docs/BuJo_Visual_Specification_v1.md
就已經提供了一個非常重要的資訊：
現在碰到 UI 任務，你應該去哪裡找真正的規格。
需要時再去讀。
不需要時，就不用每次都把整本文件一起扛在身上。
對我來說，這很像不是把整間圖書館搬到 AI 面前，而是先給它一張索引：
「你要找的那本書，在第三排。」
這時又會碰到另一個很實際的問題。
假設專案裡同時有：
CLAUDE.md
AGENTS.md
而兩份裡面有很多共同規則。
難道同一件事要維護兩次嗎？
今天 AGENTS.md 更新了。
明天忘記同步 CLAUDE.md。
最後兩個 Coding Agent 拿到的規則又開始不一樣。
而 Claude Code 官方其實直接提供了一個很好用的解法：
Import。
CLAUDE.md 可以用：
@path/to/file
引用其他文件。
所以如果團隊決定把跨工具共用的規則集中放在 AGENTS.md，就可以直接在 CLAUDE.md 寫：
@AGENTS.md
讓 Claude Code 一起載入它。
也就是：
AGENTS.md
↓
共通的 Agent 規則
CLAUDE.md
↓
@AGENTS.md
↓
Claude Code 讀取共通規則
這是 Claude Code 官方提供的 Import 機制。
不是 AGENTS.md 這個格式本身規定的特殊語法。
但它剛好可以解決多工具協作時很麻煩的一件事：
同一份共同規則，不需要複製兩次。
讓其中一份成為 Single Source of Truth（單一真理來源），另一份直接引用。
畢竟建立這些規則，本來就是為了減少混亂。
如果最後反而留下兩份幾乎一模一樣、還要人工祈禱它們永遠同步的文件，就有點本末倒置了。
回頭看 BuJo，我們前後端其實都有自己的 AI 指令檔。
而且裡面留下的，也真的有那些「AI 光看 Code 不一定知道」的事情。
像後端會提醒：
修改資料模型時，要搭配對應 migration。
前端則直接指向視覺規格文件，提醒 AI 做介面實作時要遵守那份 Specification。
一個留下固定的處理方式。
一個告訴 AI 真正的規格去哪裡找。
現在重新看，我反而覺得這比把整個專案重新介紹一次實用很多。
想像我第一次開 Claude Code，很認真地說：
「改 Schema 記得做 migration。」
「UI 記得看視覺規格。」
「改完記得跑測試。」
第二次開新的 Session，再講一次。
到了第五次開始覺得：
「這個我之前不是講過了嗎？」
結果少提醒了一條。
換成隊友開另一個 Coding Agent，那個 Agent 更是從頭到尾都沒有聽過。
這些規則如果一直存在人的記憶和當下 Prompt 裡，不只要重複花時間溝通，每個人交給 AI 的「專案規則版本」也可能慢慢不一樣。
少掉重複解釋，自然也可以減少一部分重複 Prompt 帶來的 Token 和溝通成本。
但反過來，如果我因此把所有專案資訊全部塞進去，也只是從另一邊浪費 Context。
Coding Agent 每次開工，都得先處理一次它自己其實找得到的事情。
真正重要的那幾條規則，反而被一大堆資訊淹沒。
沒有規則會亂；規則太多，也一樣會亂。
我現在最在意的，是 CLAUDE.md / AGENTS.md 寫好之後還要一直被維護。
我原本很容易把這類東西想成：
「太好了！設定完成，以後就不用管了。」
但 Codebase 會改。
工作流程會改。
Coding Agent 自己的能力也會一直變。
今天很重要的一條提醒，幾個月後可能早就已經不是問題。
如果每次 AI 犯錯就加一條，卻從來不刪，最後這份文件一定會越來越肥。
甚至可能同時存在：
現在的規則
過去的規則
重複的規則
互相打架的規則
原本拿來減少溝通的工具，反而開始製造新的誤解。
所以我現在反而會把它理解成一份 活文件（Living Document）。
踩到新的雷，可以新增。
專案改變了，就修改。
已經不再需要的護欄，也要敢刪。
它不是一次寫到完美的規格書。
比較像一座需要一直整理的花園。
真正讓 AI 長期更懂專案的，不是第一次把規則寫得多完整。
而是一直有人回頭問：
「這一條，現在還值得 AI 每次開工都先知道嗎？」
值得，就留下。
不值得，就修掉。
到這裡，「規劃設計」這一關也差不多走完了。
明天開始正式進入核心開發——如果專案換一台電腦，為什麼不能只靠一句：
「可是我這裡明明跑得動呀？」
下一篇，就從環境建置和 package.json 開始拆。
iThome鐵人賽
看影片追技術
看更多